Working through these tutorials in order is the best way to learn to build
GUI's with AWNPipe. A few minutes here will save you hours of development
time later.
TUTORIAL 1
-----------
Building GUIs ca be VERY easy, This first tutorial will develope a simple GUI.
Create a simple 4 line text file called first.gui . (you can dragselect and the Right Amiga C to copy text from thedse docs)
title "My first GUI" defaultgadgets
button gadgettext "YES"
button gt "NO"
open
Now in a shell 'copy first.gui awnpipe:/xc'.
That was easy. You already guessed that gt was a short form for gadgettext.
Now we want to see what events the GUI sends. We can direct the events to a con by adding 'wcon:' to the end of the pipe name. Try
'copy first.gui awnpipe:/xcwcon:'
Notice that the pipe replies to each line of the definition file as well as sending events.
Now add a little text to the gui. We will also provide keyboard shortcuts for the gadgets.
title "My first GUI" defaultgadgets
label gt " Select YES or NO "
button gadgettext "_YES"
button gadgettext "_NO"
open
Thats worked, but it looks a little UGLY. Lets try a vertical layout instead of horizontal (the default).
title "My first GUI" defaultgadgets vertical
label gt " Select YES or NO "
button gadgettext "_YES"
button gadgettext "_NO"
open
Getting better but we realy want the two gadgets side by side. To do that we will use a layout group. (le is layout end).
title "My first GUI" defaultgadgets vertical
label gt " Select YES or NO "
layout
button gadgettext "_YES"
button gadgettext "_NO"
le
open
Thats much better! Looks good but it would be nicer if the window closed after the user selected yes or no. ( you also notice that the layout recieved a GID number so yes and no are now gadget 2 and 3)
title "My first GUI" defaultgadgets vertical
label gt " Select YES or NO "
layout
button gadgettext "_YES" close
button gadgettext "_NO" c
le
open
Its done, it might even be usefull.
Since we have a working gui lets use it to see a few other types of events the GUI can generate.
title "My first GUI" defaultgadgets vertical sendkeys sendqual help state
label gt " Select YES or NO "
layout
button gadgettext "_YES" close
button gadgettext "_NO" c
le
open
Activate and inactivate the window. Hold the mouse over each gadget. Type a few keys. Try the shift, alt ect.
TUTORIAL 2
-----------
Now that we know how to designed a gui we want to be able to operate one.
To follow this example you need a basic knowledge of ARexx. Have a look at
the file Tutorial2.rx in the demos drawer.
The program flow is straight forward. 3 simple steps.
1. Default values are set. These are the values of the gadgets when
the GUI opens.
2. A routine (buildgui) is called to write the GUI definition to the pipe.
(More on this routine later)
3. Events are read from the pipe and processed untill the stream of events
ends.
BUILDGUI
The 'buildgui' routine contains the information defining the GUI window and
its gadgets. The data is sent line by line to the 'topipe' routine which sends
the data to the pipe, checks for errors, and returns the GID returned by the
pipe. (more on 'topipe' later.)
For most lines sent with 'topipe' the responce is ignored. For gadget
definitions however the return value is stored so we can identify gadget
events later on.
TOPIPE
This routine takes a line of text and writes it to the pipe. The pipes
responce is read. If everything is ok the second parameter of the responce is
returned. This is the GID if a gadget is defined and a null string in most
other cases. If an error ocurs the problem line is output and the script
exits.
You should use this routine or one like it when writing your own script for
AWNPipe. It will help avoid common errors and make debugging much easier.
EVENT HANDLING
The main loop reads an event from the pipe and parses it into its parts.
The first word of an event always tells the event type. This information is
used to call a routine for that type of event.
CLOSE EVENT
If a close event is received write a little text and then exit the script.
GADGET EVENT
We check the second word of the event to see which gadget sent the event. For
most gadgets we store event information and return. If the cancel gadget is
the cause of the event we output some text and exit. If it was the done gadget
we output the information for each gadget and exit. If it was the reset gadget
we close the pipe, then create the gui again to restore the default values.
MENU EVENT
The second word of a menu event is the menu number, the third word id the
item number, and the forth the subitem number. This information is used to
determine what action should be taken in responce to an event.
Almost any GUI can be operated using this aproach demonstated in this
tuorial.
TUTORIAL 3
---------------
This tutorial deals with modifying a GUI after it has been opened. You
should make sure you understand tutorial 2 before reading further.
Three new gadgets have added to the gui. The load and save gadgets on the
lower left, and a get file gadget that you do not see. The getfile gadget is
unattached (ua) so it does not have aplace in the gui. More on the getfile
gadget later.
The window definiton line (in buildGUI:) has the modify option added to it.
This means the pipe will look for modify commands after you fist open the
window, and after each event is sent. Any number of modify commands can be
written to the pipe, including 0 (none). After writing the modify comands
'continue' must be sent to the pipe to tell it to start sending events.
Only two changes are made in the program flow.
1. After BUILDGUI is called to build and open the window we send a modify
command to the pipe.
topipe('id 'savegad' dis 1 ref')
The id specifies the save gadget, 'dis 1' disables it, and 'ref' refreshes
it so the changes will show. (we want the save gadget disabled because the
name gadget is empty at start up, and we need a name before we can save).
2. In the mail loop a 'continue' is written to the pipe BEFORE we wait for an
event. This tells to pipe to stop looking for modify commands and send an
event.
After an event is read from the pipe it automaticaly starts looking for more
modify events. This means that modify commands can be used imediatly after
receiving an event from the pipe.
RESETFORM
In tutorial 2 we had to close then open the GUI to reset its contents. With
modify commands we can do this with the gui remaining open. The function
restform is near the end of tutorial3.rx.
This function sends a modify command for each of the gadgets resetting them
to the default values. It also disables the save gadget.
SAVEFORM
This function is called when the user hits the save gadget. It writes the
forms contents to a file in 't:'. The files name is the text from the name
gadget with '.formdemo' appended to it. The save gadget is disabled unless
the name gadget contains text. See the handling of namegad in the GADGET:
routine.
LOADFORM
This function makes use of the unattached GETFILE gadget. A modify command
is used to set the file name in the file requester, and to open the requester
itself. The pattern used in the file requester was set when the gadget was
created in the BUILDGUI routine.
call writeln(ca,'id 'getfilegad' fn "t:" s 1')
'fn "t:"' sets the file requester to the drawer T:. 's 1' opens the
requester.
The return from the pipe to this modify command is read and parsed to get
the file selected and to test if the user selected a file or aborted the
requester. The reply from the pipe is ...
SUCCESS ["filename"]
Success is 0 if the user aborts the file requester, non zero if a file is
selected. The file name is allways returned in quotes since multiple files
can be slected in some situations. (but not this situation).
If the user selected a file, it is opened and the contents placed in the
GUI. No error checking is done on the file in order to keep the tutorial
clear and easy to understand.
TUTORIAL 4
---------------
Now for some simpler (but powerfull ideas).
Some interesting things can be done by setting a few simple aliases.
alias see echo >awnpipe:/xc "defg*nbitmap fn []*nimage*nopen"
Now 'see FILENAME' will display pictures using your datatypes.
alias toolt type awnpipe:/xi[]
Now 'toolt FILENAME' will display the tooltypes of FILENAME. (do not include .info in FILENAME).
